<ui:composition template="/WEB-INF/templates/showcase.xhtml"
	xmlns="http://www.w3.org/1999/xhtml"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html"
	xmlns:ui="http://java.sun.com/jsf/facelets"
	xmlns:o="http://omnifaces.org/ui"
>
	<ui:define name="description">
		<p>
			The <code>omnifaces.SelectItemsConverter</code> allows you to populate e.g. a drop-down with complex Java 
			model objects as value of <code>&lt;f:selectItems&gt;</code> and have JSF convert those automatically back 
			without the need to provide a custom converter which may need to do the job based on possibly expensive 
			service/DAO operations.
		</p>
		<p>
			The base converter uses by default the <code>toString()</code> method of the object to uniquely identify 
			the object during the conversion. Since this is not the typical use case for <code>toString()</code>, it is
			recommended to extend the <code>SelectItemsConverter</code> class and override <b>only</b> the 
			<code>getAsString</code> method wherein the desired implementation is provided.
		</p>
		<p>
			For example:
		</p>
		<pre class="prettyprint"><code class="code-java">
@FacesConverter("exampleEntitySelectItemsConverter")
public class ExampleEntitySelectItemsConverter extends SelectItemsConverter {

    @Override
    public String getAsString(FacesContext context, UIComponent component, Object value) {
        Long id = (value instanceof ExampleEntity) ? ((ExampleEntity) value).getId() : null;
        return (id != null) ? String.valueOf(id) : null;
    }

}
		</code></pre>
		<p>
			Again, you do not need to override the <code>getAsObject()</code> method which would only need to perform
			possibly expensive service/DAO operations. The <code>SelectItemsConverter</code> base converter will do it
			automatically based on the available items.
		</p>
		<p>
			The below demo uses the base converter only, as <code>ExampleEntity</code> already returns its unique 
			identifier in the <code>toString()</code> method. If you intend to use the extended select items converter
			for your entities based on the above example, then just specify the converter as 
			<code>converter="exampleEntitySelectItemsConverter"</code> instead.
		</p>
	</ui:define>

	<ui:define name="demo">
		 <h:form>
			<p>
				<h:outputText id="selected_item" value="Last selected item: #{selectItemsBean.selectedEntity.value}" /> 
			</p>
			
			<h:panelGrid columns="2">
				<h:outputLabel for="iterator" value="Items with iterator: " />
				<h:selectOneMenu id="iterator" value="#{selectItemsBean.selectedEntity}" converter="omnifaces.SelectItemsConverter">
					<f:selectItem itemLabel="Choose item" noSelectionOption="true" />
					<f:selectItems value="#{selectItemsBean.exampleEntities}" var="entity" itemLabel="#{entity.value}" itemValue="#{entity}" />
					<f:ajax render="selected_item" />
				</h:selectOneMenu>

				<h:outputLabel for="iterator_def_value" value="Items with iterator (default value): " />
				<h:selectOneMenu id="iterator_def_value" value="#{selectItemsBean.selectedEntity}" converter="omnifaces.SelectItemsConverter">
					<f:selectItem itemLabel="Choose item" noSelectionOption="true" />
					<f:selectItems value="#{selectItemsBean.exampleEntities}" var="entity" itemLabel="#{entity.value}" />
					<f:ajax render="selected_item" />
				</h:selectOneMenu>

				<h:outputLabel for="selectitems" value="Items with SelectItem list: " />
				<h:selectOneMenu id="selectitems" value="#{selectItemsBean.selectedEntity}" converter="omnifaces.SelectItemsConverter">
					<f:selectItem itemLabel="Choose item" noSelectionOption="true" />
					<f:selectItems value="#{selectItemsBean.selectItems}" />
					<f:ajax render="selected_item" />
				</h:selectOneMenu>

				<h:outputLabel for="selectitems_array" value="Items with SelectItem array: " />
				<h:selectOneMenu id="selectitems_array" value="#{selectItemsBean.selectedEntity}" converter="omnifaces.SelectItemsConverter">
					<f:selectItem itemLabel="Choose item" noSelectionOption="true" />
					<f:selectItems value="#{selectItemsBean.selectItemArray}" />
					<f:ajax render="selected_item" />
				</h:selectOneMenu>
			</h:panelGrid>
		</h:form>
	</ui:define>
</ui:composition>